Node / meshtastic / Meshtastic-Android / files / .github / agents / speckit.brownfield.migrate.agent.md

Displaying Rendered • View raw • Download

description: Incrementally adopt SDD for existing features with reverse-engineered

specs

<!-- Extension: brownfield -->

<!-- Config: .specify/extensions/brownfield/ -->

Reverse-engineer spec-kit artifacts (spec.md, plan.md, tasks.md) for features that were built before spec-kit was adopted. This brings existing work into the SDD workflow so teams can track, refine, and extend features using spec-kit commands.

T282828

You MUST consider the user input before proceeding (if not empty). The user may specify a feature or module to migrate (e.g., "auth system", "payments module"), a branch name, or "all" to migrate everything.

1. Verify a spec-kit project exists by checking for T383838.specify/ directory

2. Verify git is available and the project is a git repository

3. Verify the project has existing source code to migrate (not an empty project)

4. Verify constitution exists (recommend running T383838/speckit.brownfield.bootstrap first if missing)

1. Identify migration targets: Determine what to migrate based on user input:

2. Detect feature boundaries: For each migration target, determine its scope:

• Files: Which source files implement this feature

• Tests: Which test files cover this feature

• Dependencies: What other modules or services this feature depends on

• API surface: Endpoints, functions, or interfaces exposed by this feature

• Database: Migrations, models, or schema changes related to this feature

3. Reverse-engineer spec.md: Analyze the code to reconstruct what the feature does:

• User scenarios: Infer from test cases, route handlers, and UI components

• Requirements: Extract from code behavior, validation rules, and error handling

• Success criteria: Derive from test assertions and acceptance patterns

• Assumptions: Note any hardcoded values, environment dependencies, or implicit requirements

• Mark the spec as T383838status: migrated to distinguish from specs created through the normal workflow

4. Reverse-engineer plan.md: Reconstruct the implementation approach:

• Technical context: Actual frameworks, libraries, and patterns used

• Project structure: Where the feature's code lives in the project

• Complexity assessment: Based on file count, line count, and dependency depth

5. Reverse-engineer tasks.md: Create a task list reflecting what was actually built:

• Each major component or module becomes a task group

• Mark all tasks as T383838[x] (completed) since the feature already exists

• Include test tasks based on actual test files found

• Note any gaps: code without tests, features without error handling

6. Create feature branch and artifacts: For each migrated feature:

• Create a feature directory: T383838specs/{feature-name}/

• Write T383838spec.md, T383838plan.md, and T383838tasks.md into the feature directory

• Do not create a git branch — the feature already exists on its branch or main

7. Present migration plan: Show what will be created before writing:

T282828

| Ta5d6ff`specs/user-auth/spec.md` | 4 user scenarios, 12 requirements, 6 success criteria |

| Ta5d6ff`specs/user-auth/plan.md` | 3 implementation phases, 8 technical decisions |

| Ta5d6ff`specs/user-auth/tasks.md` | 14 tasks (all completed), 2 gaps identified |

## Gaps Found

Tff7b72- ⚠️ No error handling tests for expired tokens

Tff7b72- ⚠️ No rate limiting on login endpoint

Proceed with migration?

8. Execute migration: After user confirmation, write all artifacts.

9. Report:

T282828

Tff7b721. No error handling tests for expired tokens → consider Ta5d6ff`/speckit.specify` for a follow-up feature

Tff7b722. No rate limiting on login endpoint → consider Ta5d6ff`/speckit.bugfix.report` to track

## Next Steps

Tff7b72- Review generated artifacts in Ta5d6ff`specs/user-auth/`

Tff7b72- Use Ta5d6ff`/speckit.refine.update` to adjust any inaccurate specs

Tff7b72- Use Ta5d6ff`/speckit.specify` for new features — they'll follow the same SDD workflow

Tff7b72- Run Ta5d6ff`/speckit.brownfield.migrate` again for additional features

• Always confirm before writing — show the migration plan and wait for user approval

• Honest assessment — if the code is unclear or poorly documented, say so in the spec rather than inventing explanations

• Mark as migrated — all migrated specs must include T383838status: migrated to distinguish from fresh specs

• Identify gaps — actively look for missing tests, error handling, or documentation and report them

• Non-destructive — never modify existing source code, only create spec artifacts

• One feature at a time — for "all" input, migrate features sequentially with confirmation between each

• Respect constitution — generated artifacts must follow the project's constitution rules